/**
 * $RCSfile$
 * $Revision: 3174 $
 * $Date: 2005-12-08 17:41:00 -0300 (Thu, 08 Dec 2005) $
 *
 * Copyright (C) 2005-2008 Jive Software. All rights reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package net.lastcoder.ifserver.session;

import net.lastcoder.ifserver.nio.Connection;
import net.lastcoder.ifserver.packet.Packet;

import java.net.UnknownHostException;
import java.util.Date;

/**
 * 所有的连接都通过这个会话来进行管理
 */
public interface Session {
    /**
     * 会话为关闭状态
     */
    public static final int STATUS_CLOSED = -1;
    /**
     * 会话为连接状态
     */
    public static final int STATUS_CONNECTED = 1;
    /**
     * 会话已经授权
     */
    public static final int STATUS_AUTHENTICATED = 3;

    /**参与{@link UlaID}
     * @return 得到地址
     */
    public UlaID getAddress();

    /**
     * @return 得到用户名
     */
    public String getUsername();

    /**参阅 {@link #STATUS_AUTHENTICATED} {@link #STATUS_CONNECTED} {@link #STATUS_CLOSED}
     * @return 得到状态
     */
    public int getStatus();

    /**
     * @param status 设置状态
     */
    public void setStatus(int status);

    /**
     * @return 创建时间
     */
    public Date getCreationDate();

    /**
     * @return 最后一次发送数据书剑
     */
    public Date getLastActiveDate();

    /**
     * @return 得到客户端发送包数量
     */
    public long getNumClientPackets();

    /**
     * @return 得到服务器下发的包数量
     */
    public long getNumServerPackets();

    /**
     * 关闭会话
     * <ul>
     *      <li>设置为close状态
     *      <li>关闭会调 {@link SessionListener#sessionDestroy(Session)}
     *      <li>关闭socket连接
     * </ul>
     */
    public void close();

    /**
     * 是否关闭
     *
     * @return true or false
     */
    public boolean isClosed();

    /**
     * 返回IP
     *
     * @return  IP地址
     * @throws UnknownHostException 无法识别
     */
    public String getHostAddress() throws UnknownHostException;

    /**
     * @return 返回host地址name
     */
    public String getHostName() throws UnknownHostException;

    /**注意这里的数据是json还是binary
     * @param data 发送raw数据
     */
    public void deliverRawData(byte[] data);
    public void deliverRawData(byte[] data, int off, int len);

    /**发送一个包
     * @param packet
     */
    public void process(Packet packet);

    /**
     * @return 得到这个会话的名字
     */
    public String getName();

    /**冲突次数会在指定的时间过后重置为0
     * @return 得到冲突次数
     */
    public int getConflictCount();

    /**得到一个自定义的属性
     * @param key
     * @return
     */
    public Object getAttribute(String key);

    /**设置一个自定义的属性
     * @param key
     * @param object
     */
    public void setAttribute(String key, Object object);

    public Connection getConnection();
}